home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-02
/
tpbook.zip
/
TPBOOK.EXE
/
TPR9.TXT
< prev
Wrap
Text File
|
1992-10-19
|
75KB
|
1,747 lines
Chapter 9
of the
Turbo Pascal Reference
The Turbo Vision Reference
(continued)
This chapter is part of the Turbo Pascal Reference electronic freeware book (C)
Copyright 1992 by Ed Mitchell. This freeware book contains supplementary
material to Borland Pascal Developer's Guide, published by Que Corporation,
1992. However, Que Corporation has no affiliation with nor responsibility for
the content of this free book. Please see Chapter 1 of the Turbo Pascal
Reference for important information about your right to distribute and use this
material freely. If you find this material of use, I would appreciate your
purchase of one my books, such as the Borland Pascal Developer's Guide or
Secrets of the Borland C++ Masters, Sams Books, 1992. Thank you.
For additional information on using Turbo Vision, including a detailed
tutorial, please see Chapters 11 through 16 of the Borland Pascal Developer's
Guide.
TFrame object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TFrame
Discussion
TFrameobjects, like many of the objects in Turbo Vision, are automatically
managed by Turbo Vision and you will rarely need to instantiate, let
alone, directly access any of its methods. The TFrame object defines the
border or "frame" that wraps around each window and is automatically
created by TWindow.Init which calls TWindow.InitFrame.
Fields
None
Methods
procedure Draw; virtual;
This method draws the frame, adding the owner's Title string, and the
appropriate icons such as the close box, the zoom icon and the resize
icon, as specified by the inherited TView.State flags.
function GetPalette: PPalette; virtual;
Returns a pointer to the default palette CFrame. In the unlikely event
that you need to change a TFrame's color, you need to override
TWindow.InitFrame to instantiate a new, TFrame-derived object with an
overridden GetPalette. The overridden GetPalette then returns a pointer
to the modified color palette mapping. You need to go through this
indirect approach of overriding both TWindow.InitFrame and creating a new
TFrame-type object because TFrame is normally used only internally to
Turbo Vision. Hence, you must override the routine in TWindow that
actually instantiates the TFrame. You can see an example of this type of
operation in the description of TBackground.
procedure HandleEvent(Event : TEvent);
Calls TView.HandleEvent for general event processing, and then processes
events for the TFrame icons.
constructor Init(var Bounds: TRect);
Creates a new TFrame object having the size and location specified by
Bounds. This method is called by TWindow.InitFrame.
See: TWindow.InitFrame
procedure SetState(AState: Word; Enable: Boolean; virtual;
TFrame.SetState passes its parameters to TView.SetState, and then checks
TView.State to see if either sfActive or sfDragging are set. If these
bits are set, then TFrame.SetState calls TView.DrawView.
TGroup object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TGroup
TWindow
TDialog
TDeskTop
TProgram
Discussion
The TGroup object manages groups of objects, all of which are descended
from TView. In effect, TGroup keeps track of a group of subviews, such as
multiple windows on the desktop, or all of the controls within a dialog.
TGroup provides the functionality to manipulate the grouped views as if
they were a single view, although TGroup itself, surprisingly, is an
invisible view. That's because each of the subviews contained within a
group defines the group itself. For example, a TDialog contains a window,
a frame, a dialog interior and a collection of controls such as input
lines, checkboxes and buttons. The TDialog object is the manager of these
dialog box components and is actually invisible. WhenTDialog.Draw is
called to draw itself on the screen, it doesn't actually draw anything;
instead, TDialog.Draw calls each of the subview's Draw methods (the
window, the frame, the buttons and so on).
Commonly Used Features
For most applications you will use only a few of the methods provided by
TGroup, including the Init constructor (via the subview's inherited Init
methods), ExecView to execute a modal dialog box, Insert to add a subview
to the group, and GetData and SetData to read and write the data fields of
the owned views (particularly for dialogs). TGroup is an internal object
used to support other Turbo Vision objects (such as TWindow or TDialog),
and the remaining methods are used to implement their specific
functionality. It is unlikely that you will need to instantiate a TGroup
directly.
Example
See TApplication, TDeskTop, TDialog, TWindow
Fields
Buffer: PVideoBuf; { Read only }
When caching of views is in effect, the contents of the group of views is
stored in a temporary cache buffer to speed up screen redrawing. Buffer
points to the memory buffer used for caching, or is nil if no cache buffer
has been defined.
See GetBufMem, TGroup.Draw, TGroup.Lock, TGroup.Unlock
Current: PView; { Read only }
Is a pointer to the currently selected view (the view whose Select method
has been called).
See: TView.Select, Chapters 16 and 18.
Last: PView; { Read only }
Last is a pointer to the subview that is on the bottom of the Z-ordered
list of views. Each view contains a TView.Next pointer that points to the
next view in the list.
Phase: (phFocused, phPreProcess, phPostProcess); { Read only }
Subviews can examine this field to determine at which phase in the event
processing their HandleEvent method was called. See Chapter 13, "More
Turbo Vision Features" in the Borland Pascal Developer's Guide for a more
in depth discussion of phased event processing.
Methods
procedure ChangeBounds(var Bounds: TRect); virtual;
Override: Never
A group is resized or moved by calling ChangeBounds, which, in turn, calls
TView.CalcBounds to recalculate new boundaries for its subviews, and then
ChangeBounds to reposition the subviews. These calls are made for every
subview in the group.
function DataSize: Word; virtual;
Calls each subview's DataSize method and creates a total data size value
for the entire group. This function is normally used in conjunction with
GetData and SetData for retrieiving specific field values.
procedure Delete(P: PView);
Use Delete to remove a previously inserted view from a group. For
example, if you have inserted a view, like this,
Insert(DirWindow);
you remove the subview by calling,
Delete(DirWindow);
destructor Done; virtual;
Call Done to dispose of the group and its contents. Done first hides the
group and then calls each view's Done destructor, and finally disposes of
itself.
procedure Draw; virtual;
If Buffer is nil, then TGroup.Draw calls each subview's Draw method. If
Buffer is not nil, then Draw calls TView.WriteBuf to copy the cached view
image to the screen.
See: TGroup.Buffer
procedure EndModal(Command: Word)(; virtual;
Override: Never
When the currently active dialog, for instance, that has been placed on
the screen with the TGroup.ExecView method, it is the current modal view.
A call to this procedure terminates the modal nature of the view and
passes the Command value to ExecView, which in turn, returns Command to
the caller. If a group is not currently a modal view, TGroup.EndModal
calls TView.EndModal which has approximately the same result, causing
ExecView to return Command to its caller.
See: TView.EndModal
procedure EventError(var Event: TEvent); virtual;
If TGroup.Execute encounters an event that it cannot handle, it first
calls TGroup.EventError, which attempts to call its owner's EventError
method. You can override this function to intercept errors, if needed.
function ExecView(P: PView): Word;
Besides Init, Done and Insert, this is one of the most commonly used
methods in a TGroup object. Call ExecView to display a modal view, such
as a dialog box, on the screen. When a modal view is on the screen, all
events are handled by the modal view. You can not, for instance, make
menu selections or press short cut keys to activate non-dialog box
functions. You must first terminate the modal dialog before resuming
regular program operation. ExecView returns the command code that caused
the view to complete. This might be cmOk, cmCancel or some other code
that you have defined as part of the dialog definition.
See: TGroup.Insert, TGroup.Delete, Chapter 12
function Execute: Word; virtual;
Execute is the TGroup's main event processing loop, fetching events and
then calling HandleEvent to process each event. The loop is terminated
when a view calls EndModal. Execute returns the command code that caused
the termination, and that is passed to ExecView for return to the caller.
See: TGroup.EndModal, TGroup.HandleEvent
function First: PView;
Returns a pointer to the subview within the group that is currently "on
top" or closest to the screen. If, for some reason, this is called when
the group has no subviews, First returns nil.
function FirstThat(Test: Pointer): PView;
Test is a pointer to a far local function having one Pointer parameter and
returning either True or False. This iterator function operates
identically to the TCollection.FirstThat iterator, except that
TGroup.FirstThat scans through the list of subviews within the group, in
Z-order (see Chapter 13, "More Turbo Vision Features".)
See: Chapter 14, "Collections", TCollection.FirstThat
procedure ForEach(Action: Pointer);
Action is a pointer to a far local procedure having one Pointer (or PView)
parameter. ForEach scans through the subviews in Z-order, and for each
subview it calls the Action procedure with a pointer to the subview.
TGroup.ForEach operates similarly to TCollection.ForEach, except that you
should normally call TGroup.Lock prior to calling TGroup.ForEach, and
TGroup.Unlock after calling ForEach. This is particularly important when
the ForEach iterator is used such that each subview is redrawn on the
screen and TGroup is using a cache Buffer. Lock causes subsequent screen
writes to go only to the cache Buffer, and Unlock then copies the entire
Buffer to the screen. If you do not use Lock/Unlock, each of the subviews
will repaint on the screen individually, causing a potentially annoying
visual effect.
See: Chapter 14, "Collections", TGroup.Buffer, TGroup.Lock, TGroup.Unlock
procedure GetData(var Rec); virtual;
Calls each subview's GetData procedure in reverse Z-order, copy each
subview's data to the Rec variable. After calling each subview's GetData
procedure, GetData adds the subview's DataSize value to Rec so that Rec
now points past the data it just copied, making it ready to read the next
subview's data.
See: TView.DataSize, TGroup.SetData
function GetHelpCtx: Word; virtual;
Calls the currently Selected subview's GetHelpCtx to return the subview's
context sensitive help index. If the subview doesn't have any context
sensitive help, then GetHelpCtx returns the value of the help context for
the entire TGroup.
procedure GetSubViewPtr(var S: TStream; var P);
This procedure is called from within TGroup.Load to read a subview pointer
P from stream S.
See: TGroup.Load, TGroup.PutSubViewPtr, TGroup.Store
procedure HandleEvent(Event: TEvent); virtual;
The TGroup.HandleEvent method passes most events onto the appropriate
subview's HandleEvent method according to whether the event is a focused
event, positional event or broadcast event. See Chapters 12 and 13 in the
Borland Pascal Developer's Guide for a detailed description of event
processing.
constructor Init(var Bounds: TRect);
TGroup's Init method calls TView.Init, and sets the TView.Options variable
to ofSelectable and ofBuffered. The latter option enables cache buffering
of the view's Draw output, if sufficient memory is available. TView's
EventMask field is set to $FFFF which causes this view (or group) to
respond to all classes of events.
procedure Insert(P: PView);
Use Insert to place a non-modal view into the group. For example, Insert
is used to place windows onto the TDeskTop group object, as well as all of
the individual controls within a dialog object.
See: TGroup.Delete, TGroup.ExecView, TGroup.InsertBefore
procedure InsertBefore(P, Target: PView);
InsertBefore enables you to insert a view at any location within an
existing group. The view P becomes inserted before (in Z-Order) the view
specified by Target. If Target is nil, then P is inserted at the very
back of the view, furthest from the screen.
constructor Load(var S: TStream);
Load creates a new TGroup object and reads each subview from stream S.
procedure Lock;
When using the cache Buffer to speed up screen output, setting Lock
prevents the Buffer contents from being written to the screen. This way,
multiple items or views can be written to the Buffer without causing
annoying flicker, and then by calling Unlock, the entire Buffer is copied
to the screen in one operation. Lock operates by incrementing a lock
counter each time that it is called. Unlock decrements the counter and
once the counter reaches zero, copies the Buffer to the screen.
Important: Lock and Unlock must always be called in matched pairs to
avoid leaving the Buffer in a locked state. If that happens, no output
will be sent to the screen.
See: GetBufMem, TGroup.ForEach, TGroup.Unlock
procedure PutSubViewPtr(var S: TStream,; P: PView);
This method is used in conjunction with the TGroup.Store method to write a
subview pointer to stream S.
See: TGroup.GetSubViewPtr, TGroup.Load, TGroup.Store
procedure Redraw;
Redraw forces an actual screen draw to occur, rather than merely copying
from the cache Buffer. Otherwise, Redraw is the same as TGroup.Draw.
procedure SelectNext(Forwards: Boolean);
SelectNext complements the TView.Select method for making a view the
focused view. If Forwards is True, then the next subview in Z-Order
from the currently selected view becomes the focused view. If Forwards is
False, then SelectNext moves to the previous subview.
procedure SetData(var Rec); virtual;
SetData is used in conjunction with GetData for accessing the data in the
group. SetData calls each subview's SetData method, copying data from Rec
to the subviews.
procedure SetState(AState: Word; Enable: Boolean); virtual;
TGroup.SetState sets or clears the bits in each subview's State field, to
accomodate setting focused, active, exposed or dragging bits within State.
See: TView.SetState, sfXXXX constants
procedure Store(var S: TStream);
Outputs all the TGroup and all of its subviews to stream S.
procedure Unlock;
Unlocks a previously locked cache Buffer and copies the contents of the
Buffer to the screen.
See: TGroup.Locked
function Valid(Command: Word): Boolean; virtual;
If all of the subview's Valid functions return True, then TGroup.Valid
returns True, otherwise TGroup.Valid returns False. Since Valid is called
when the Execute procedure is going to exit, a subview can retain control
and prohbit the group from terminating by setting its Valid function to
return False.
See: TGroup.Execute, TView.Valid
THistory object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
THistory
Discussion
THistory implements the history windows that display a down arrow icon on
the right hand side of dialog input fields. Using THistory, a history of
previously entered data is retained for future reference. Each time you
enter a new value into an input field that is linked to a THistory object,
the old value is stored away in a THistory list. Later, when you return
to the input field, you can press down arrow or click on the down arrow
icon to open a small list viewer showing your previous entries. This
feature is especially useful in applications such as the Turbo Pascal IDE,
where you tend to refer back to files you have opened previously. Hence,
the open file dialog contains a history of the files you have recently
opened.
The THistory object is surprisingly easy to use considering the
functions that is provides. All that needs to be done is to create the
object using its Init constructor and insert it into the dialog. Data is
then automatically copied from the TInputLine field to the THistory and
back again, as appropriate.
It is not recommended that you attempt to override any of the
defined methods, except perhaps THistory.GetPalette. If you must override
any of the methods, you are strongly encouraged to view the Turbo Vision
source, available as a separate product from Borland.
Example
This short example demonstrates the use of the THistory object in a
dialog, by modifying the TShell.ConfigureData procedure of TVSHELL8 (and
example proggram shown in the Borland Pascal Developer's Guide), so that
the EditorName field now contains a THistory list. The variable AnHistory
is declared as a PHistory pointer. In the original procedure, EditorName
is declared as a PView so it is recast to a PInputLine for passing to the
THistory.Init constructor. To use THistory, define a Bounds rectangle for
the THistory icon, typically immediately to the right of the input field,
call the Init constructor, passing to it the location, a pointer to the
linked input field, and a numeric value. The numeric value (from 0 to
255) uniquely defines this THistory list so that you could gain access to
it from other fields. That means, more than one input field can reference
the same history list by always referencing the same history list number.
Alternatively, you can use different history identification numbers for
each input field and have as many separate history lists as your
application requires.
{ Editor name }
Bounds.Assign (18, 2, 50, 3);
EditorName := New( PInputLine, Init(Bounds, ConfigNameSize) );
Insert(EditorName);
{ Define the location for the THistory down arrow icon }
Bounds.Assign(50, 2, 52, 3);
AnHistory := New(PHistory,
Init(Bounds, PInputLine(EditorName), 1 ));
Insert(AnHistory);
Bounds.Assign (2, 2, 15, 3);
Insert( New (PLabel,
Init(Bounds, '~E~ditor name:',
EditorName )));
Fields
HistoryId: Word; { Read only }
Contains the history list number assigned as the third parameter to the
Init constructor.
Link: PInputLine; { Read only }
Points to the input line field's TInputLine object that is associated with
this history list.
Methods
procedure Draw; virtual;
Displays the icon representing the THistory object, at the location
determined by the Bounds parameter to Init.
function GetPalette: PPalette; virtual;
Returns a pointer to the CHistory color palette, which is intended for
mapping onto the CDialog color palette.
constructor Init(var Bounds: TRect; ALink: PInputLine; AHistoryId: Word);]
Creates the THistory object, defining its location at Bounds, and linking
to the ALink input field. AHistoryID is a number assigned by you to
uniquely identify this particular history list. If you want, you can
initialize other THistory objects that are linked to other input fields
using the same AHistory number. When the input fields have the same
AHistory number, they will all share the same history list.
constructor Load(var S: TStream);
Creates and reads a THistory object from stream S.
procedure Store(var S: TStream);
Writes this THistory object to stream S.
THistoryViewer object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TListViewer
THistoryViewer
Discussion
THistoryViewer manages the history list viewer that is displayed and owned
by THistory. Normally, you will access the THistory object when you wish
to use history lists in your applications, and will unlikely have any need
to directly use THistoryViewer.
Fields
HistoryId: Word; { Read only }
This contains the history identification number (see THistory) selecting
which history list is to be displayed in the list box managed by
THistoryViewer.
Methods
function GetPalette: PPalette; virtual;
Returns a pointer to CHistoryViewer.
function GetText (Item: Integer; MaxLen: Integer): String; virtual;
GetText is the overridden TListViewer function, implemented here to return
the specific history list string indexed by Item, such that the returned
string is less than or equal to MaxLen in size.
See TListViewer.GetText
procedure HandleEvent(var Event: TEvent); virtual;
HandleEvent processes mouse double clicks and the Enter key for selecting
a file from the list box, and pressing the Esc key in order to cancel the
list box.
function HistoryWidth: Integer;
Determines the longest string in the history list.
constructor Init
(var Bounds: TRect; AHScrollBar, AVScrollBar: PScrollBar;
AHistoryId: Word);
Calls TListViewer.Init to create a single column listbox with the
specified scroll bars, and links it to the THistory specified by AHistory.
Basically, when the THistory object is made active by selecting its icon
or pressing the down arrow key, THistory creates a THistoryWindow object
by calling InitHistoryWindow, and the THistoryWindow object, in turn,
creates this TListViewer object to display the history list and manage the
selections.
THistoryWindow object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TGroup
TWindow
THistoryWindow
Discussion
When the THistory history list icon is selected, the THistory object
creates a TWindow object in which to insert the THistoryViewer.
Therefore,the THistoryWindow is primarily useful to the implementation of
THistory and is not likely to be used directly by your programs. See the
THistory object for an example use of history lists.
Fields
Viewer: PListViewer;
Contains a pointer to the THistoryViewer list box that is created by this
object.
Methods
function GetPalette: PPalette; virtual;
Returns a pointer to CHistoryWindow, which is designed to map onto a
dialog palette.
function GetSelection: String; virtual;
Determines which list box item in the THistoryViewer has the focus, and
returns that specific string.
constructor Init(var Bounds: TRect; HistoryId: Word);
Creates the THistoryWindow by calling TWindow.Init with appropriate
parameters, and then calls InitViewer.
procedure InitViewer(HistoryId: Word); virtual;
This is the routine that creates the THistoryViewer list box.
TInputLine object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TInputLine
Discussion
Use TInputLine as an edit field in dialog boxes when you need to have the
user type in information such as a filename or other text. TinputLine is
a powerful single line editor, providing horizontal scrolling, line
editing, text selection and block deletion. If the size of the input line
field is less than the maximum permitted length of the input, then
TInputLine will automatically provide left and right scrolling.
Commonly Used Methods and Fields
When TInputLine is inserted into a dialog, you will generally use
only TInputLine.Init to create the input field and will not likely have
use for any of the other methods or fields. The TInputLine will become
active when it receives the focus and will automatically process its input
via its HandleEvent method.
TInputLine processes string input however you could override
several of its methods in order to process other types of data. For
instance, to handle numeric input, you would create a new
TInputLine-derived object and override TInputLine.Valid to check for valid
numeric entries, and modify GetData to convert the entered string into a
numeric representation for processing. You would also need to modify
SetData, and if you intend to use the object with streams, you'd need to
create new versions of Load and Store.
Example
This example shows instantiating a TInputLine object having a maximum
input length of 40 character, and places within the rectangle defined by
(3, 3, 44, 4). The TInputLine object is then inserted into the dialog
group, and a TLabel is attached as a prompt. (See also TLabel). At the
completion of the dialog setup, the dialog will be displayed for editing
with Control := DeskTop^.ExecView( Dialog ); Be sure to look at the
examples in the TVSHELL program described in Chapters 11-12 of the Borland
Pascal Developer's Guide:
with Dialog^ do
begin
...
{ Add the Rename from this filename item }
Bounds.Assign (3, 3, 44, 4);
OldFileName := New( PInputLine, Init(Bounds, 40) );
Insert(OldFileName);
Bounds.Assign (2, 2, 44, 3);
Insert( New (PLabel, Init(Bounds, 'Rename this file:',
OldFileName )));
...
end; { with Dialog }
Fields
CurPos: Integer; { Read/Write }
This field is used internally to keep track of the cursor's location
within the input field.
Data: PString; { Read/Write }
Contains the pointer to the string that is being edited by the TInputLine.
FirstPos: Integer;
When horizontal scrolling is being used to display portions of the line
that do not fit within the specified bounds of the TInputLine, FirstPos
contains the index of the first byte that appears at the left of the
field.
MaxLen: Integer;
MaxLen contains the maximum number of characters for the line length, as
specified in the TInputLine.Init method.
Methods
destructor Done; virtual;
Disposes of the memory used by TInputLine and disposes of the object.
function DataSize: Word; virtual;
GetData and SetData call DataSize to determine how much space needs to be
reserved for the data returned by TInputLine. Normally this is equal to
MaxLen + 1, which is the maximum number of characters that can be entered,
plus the length byte.
See: TInputLine.GetData, TInputLine.SetData
procedure Draw; virtual;
Draw takes care of displaying the input line text on the screen, adding
arrows when horizontal scrolling is in effect.
procedure GetData(var Rec); virtual;
Copies the Data^ text string to Rec.
See: TInputLine.DataSize, TInputLine.SetData
function GetPalette: PPalette; virtual;
Returns a pointer to the CInputLine color palette. If you desire to use a
different color mapping, you should derive a new object from TInputLine
and override GetPalette as per the instructions in Chapter 13, "More Turbo
Vision Features", of the Borland Pascal Developer's Guide.
procedure HandleEvent(var Event: TEvent); virtual;
When the input line is the focused event, TInputLine.HandleEvent process
the mouse and editing keystroke events, including entering and selecting
text, horizontal scrolling and so on.
constructor Init( var Bounds: TRect; AMaxLen: Integer);
Use TInputLine.Init to create a new TInputLine object located at the
position specified by Bounds (which specifies the length of the visible
data entry field) and AMaxLen (which specifies the maximum length that the
entered string can become).
Bounds should describe a one line input field; if you specify a multi-line
rectangle, TInputLine will not behave correctly.
constructor Load(var S: TStream);
Creates and reads a TInputLine object from stream S.
procedure SelectAll(Enable: Boolean);
If Enable is True, SelectAll block selects the entire data input line and
resets all the internal pointers (such as CurPos cursor location) to the
beginning of the string. If Enable is False, all selection is turned off.
In both cases, the resultant input field is displayed on the screen by
calling the inherited TView.DrawView.
procedure SetData(var Rec); virtual;
Copies the string value in Rec to Data^ and calls SelectAll.
See: TInputLine.SelectAll
procedure SetState(AState: Word; Enable: Boolean); virtual;
Calls TView.SetState (See TView.SetState for more information) and
performs additional processing for TInputLine.
procedure Store(var S: TStream);
Writes the TInputLine object to stream S.
TItemList type
------------------------------------------------------------
Declaration:
TItemList = array[0..MaxCollectionSize-1] of Pointer;
Unit: Objects
Purpose:
This is an internal object type used for maintaining an array of pointers
in TCollection objects.
TLabel object
------------------------------------------------------------
Turbo Vision Hierarchy:
TObject
TView
TStaticText
TLabel
Discussion
TLabel objects are similar to TStaticText in that they are typically used
to display a prompt line for dialog box controls such as an input field or
a group of radio buttons. TLabel objects differ from TStaticText only in
that they are explicitly linked to the control such that if you click with
the mouse to select the TLabel object you actually select the attached
control. Using this feature, you can use keyboard Alt-letter shortcut
keys to reach input fields and other controls in a dialog box.
Example
{ Create an input line field 40 spaces wide }
Bounds.Assign(3, 3, 44, 4);
OldFileName := New( PInputLine, Init( Bounds, 40) );
Insert( OldFileName );
{ Create a prompt label for the input field and link to the
OldFileName inputline field }
Bounds.Assign( 2, 2, 44, 3);
Insert( New( PLabel, Init( Bounds, 'Rename this file:',
OldFileName )));
Fields
Link : PView { Read Only }
When a TLabel object is linked to a control, such as an input line, this
field contains a pointer to that control.
Light: Boolean; { Read Only }
Methods
procedure Draw; virtual;
Override: NEVER
Draws the TLabel object using the color palette pointed to by GetPalette.
constructor Init (var Bounds: TRect; AText; String; ALink: PView);
The Init constructor creates a new TLabel object with the size and
location specified in Bounds, and assigns to the label the text specified
in AText. The last parameter specifies a pointer to the control that is
associated with this label.
function GetPalette: PPalette; virtual;
Override: As needed to change colors.
Returns a pointer to the CLabel color palette. To change the colors of
the TLabel object, override this function to return a pointer to a
different color palette. The CLabel color palette is defined to properly
map onto a dialog's color palette. If, for some reason, you are creating
a label to be placed on top of some other type of object, you will almost
certainly need to override this function.
See: Chapter 13, "More Turbo Vision Features".
procedure HandleEvent( var Event: TEvent ); virtual;
Override: Never
HandleEvent performs the usual event processing by calling
TStaticText.HandleEvent to do most of the work. However,
TLabel.HandleEvent intercepts certain mouse down and keyboard shortcut
keys in order to select attached controls.
constructor Load( var S: TStream );
Loads a TLabel object from stream S.
See: Chapter 15, "Streams"
procedure Store( var S: TStream );
Stores this view on to stream S.
See: Chapter 15, "Streams"
TListBox object
------------------------------------------------------------
Turbo Vision Hierarchy:
TObject
TView
TListViewer
TListBox
Discussion
Use TListBox to implement list boxes containing collections of
strings. For example, a dialog box to open a file typically contains a
list of filenames and subdirectories. To use TListBox you must create and
initialize a collection of PStrings containing the items to appear in the
list box, and then instantiate and initialize the list box. While
TListBox is intended for use with string data, you can optionally override
TListBox.GetText to process non-string data. TListBox is derived from
TListViewer, so all of TListViewer's methods and fields are available to
TListBox objects.
See: TListViewer
Commonly Used Features
To use the TListBox, you'll call Init to create the box, and then NewList
to initialize the list that is displayed. If you wish to display items
other than simple strings, you'll need to override GetText.
Example
TListBox is nearly identical to TListViewer except that TListBox does not
support the horizontal scroll bar. Further, TListBox manages the data
list internally since its designed, by default to have GetText return a
string. To use TListBox, you call TListBox.Init in a manner identical to
TListViewer.Init (except that there is no horizontal scroll bar). Next,
you call TListBox.NewList to pass a collection of strings to the TListBox
for display.
Fields
List: PCollection; { Read only }
Holds a pointer to the collection of items to display. Typically this
would be a collection of PStrings, however, if you store other object
types you will also need to override GetText.
See: TListBox.GetText
Methods
constructor Init(var Bounds: TRect; ANumCols: Word; AScrollBar:
PScrollBar );
Init creates the new TListBox object using the size provided in Bounds,
the number of columns specified by ANumCols, and links it to the scroll
bar passed as the AScrollBar parameter, or nil if there is no scroll bar.
If you do add a scroll bar, you'll need to instantiate the TScroller
object prior to calling Init, and you'll need to insert both the list box
and the scroller into the owner's view. After calling Init, you should
call NewList to assign the data collection to this list box.
There is no Done destructor for TListBox since it is inherited from
TListViewer. However, you do need to dispose of the contents of List.
Oneway to do that is to call NewList(nil) which then disposes of the
current List and sets List to nil.
See: TListBox.NewList
function DataSize : Word; virtual;
Override: As needed.
This method is used in conjunction with the TListBox GetData and SetData
methods for writing and retrieving TListBox dialog data. The default
definition of DataSize returns SizeOf(Pointer) + SizeOf(Word).
See: GetData, SetData, "The List Box Viewer", in Chapter 12, "Turbo
Vision Dialogs and Events", in the Borland Pascal Developer's Guide.
procedure GetData(var Rec); virtual;
Override: As needed.
GetData copies the List and Focused (from TListViewer) fields to Rec.
See: DataSize, SetData, Chapter 12
function GetText(Item: Integer; MaxLen: Integer):String; virtual;
GetText is called by the inherited TListViewer.Draw method to obtain the
string to draw on the display. The standard implementation retrieves the
Item'th entry in the List^ collection as,
PString(List^.At(Item))^
Its possible to store non-string items in a TListBox type, but to do so
you will need to override GetText.
constructor Load( var S: TStream );
Creates and reads a TListBox object from stream S, including the data
collection linked to the list box.
See: Store, Chapter 16, "Collections".
procedure NewList(AList: PCollection); virtual;
After calling Init to create a new TListBox objecct, you need to link a
data collection to the list box. You do this by passing the collection as
a parameter to the NewList method, which sets List to point to the
collection, and sets the list box Range to the collection's Count field
and draw's the list box view by calling DrawView. If List is not nil when
NewList is called, NewList disposes of the previous collection before
setting List to the new collection.
procedure SetData(var Rec); virtual;
Copies values from Rec into the List and Focused fields and then calls
NewList(List) in order to reset and display the new list.
See: DataSize, GetData
procedure Store(var S: TStream);
Stores the contents of the list box object, including the data collection
that is pointed to by List, to the stream S.
See: Load, Chapter 15, "Streams".
TListViewer object
------------------------------------------------------------
Turbo Vision Hierarchy:
TObject
TView
TListViewer
TListBox
Discussion
Use the TListViewer object type for creating various types of list
box viewers. List boxes typically contain lists of information, such as
filenames, through which you can scroll and select the desired item.
Usingthe TListViewer object, you can create both vertical and horizontal
scroll bars. Horizontal scroll bars might be used when creating a simple
file viewer for viewing text wider than the list box.
Commonly Used Features
Call TListViewer.Init to create the list viewer. While the TListViewer
manages the display of the list box it is up to you to provide the data
structures that store the data shown within the box. You do this by
deriving a new TListViewer object type and overriding the GetText
function, which returns a string containing one line of text. GetText has
two paremeters, an item index and a maximum length value. Its up to
GetText to retrieve the Item'th entry in the list and format it into a
string of no longer than the specified maximum length. If you insert the
TListViewer into any other TGroup besides TDialog, you will almost
certainly need to override GetPalette so that the color mapping works
correctly.
Example
{ Define TDirList, derived from TListViewer }
PDirViewer = ^TDirList;
TDirList = object( TListViewer );
function GetText( Item: Integer; MaxLen: Integer):String;
virtual;
function GetPalette: PPalette; virtual;
procedure HandleEvent( var Event: TEvent); virtual
end;
...
{ Instantiate a scroll bar object }
ListScroller := New( PScrollerBar, Init( BarBounds ));
{ Instantiate a list viewer and link it to the scroll bar }
ListViewer := New( PDirViewer, Init( Bounds, 1, Nil,
ListScroller ));
{ Insert both objects into the controlling group view }
Insert(ListScroller);
Insert(ListViewer);
Fields
HScrollBar: PScrollBar; { Read only }
Holds the pointer to the horizontal scroll bar object attached to this
list viewer, or is nil if there is no horizontal scroll bar.
VScrollBar: PScrollBar; { Read only }
Holds the pointer to the vertical scroll bar object attached to this list
viewer, or is nil if there is no vertical scroll bar.
NumCols : Integer { Read only }
This stores the number of columns specified for the list viewer and is
initialized with the Init constructor.
TopItem: Integer; { Read/Write }
TopItem specifies the item appearing at the top of the list box viewer.
TopItem varies from 0 to Range-1.
Focused: Integer; { Read only }
Focused specifies the item number of the focused or selected item and
ranges from 0 to Range-1. Keyboard navigation keys, scroll bar movements
and mouse clicks and drags all cause the focused item to be updated to
point to the current location of the list box cursor.
Range: Integer; { Read only }
Holds the total number of items in the list.
See: TListViewer.SetRange
Methods
constructor Init( var Bounds: TRect; ANumCols: Integer; AHScrollBar,
AVScrollBar: PScrollBar );
Creates a TListViewer object with the size specified by Bounds and the
number of columns specified by ANumCols. If you wish to have scroll bars,
create the TScroller objects before calling Init, and then pass pointers
to those scroll bars to the AHScrollBar and AVScrollBar parameters, for
horizontal or vertical scroll bars, respectively, to link them to the list
box. Use a value of nil if one or both scroll bars is not defined for
this list box.
procedure ChangeBounds( var Bounds : TRect ); virtual;
Call ChangeBounds to resize the list box viewer to the size specified by
the Bounds parameter.
procedure Draw; virtual;
Override: Never.
Draws the list viewer object by calling GetText for each of the objects
that could be shown on the screen.
procedure FocusItem ( Item : Integer ); virtual;
Override: Never.
Use FocusItem to make a specific Item in the list box become the focused
item. This method automatically causes the scroll bar to be adjusted
accordingly.
function GetPalette: PPalette; virtual;
Override: As needed.
Returns a pointer to the color palette for TListViewer objects. The
default palette, CListViewer is intended to map directly into a CDialog
palette. If you insert the TListViewer object into a view other than the
TDialog, you must override the GetPalette function.
See: CListViewer, CDialog, Chapter 19, More on Turbo Vision
function GetText (Item : Integer; MaxLen: Integer): String; virtual;
Override: Always
You must implement your own GetText method to return a string representing
the data that should appear in the list box at the Item'th position. Your
data can be stored in whatever internal representation is appropriate for
your application. This might include a collection, an array of records, a
linked list, or a simple string array, as shown in this example code:
{ Fetch data item from internal data structure }
StrBuffer := MyData[Item];
{ Truncate data string if too long }
if Length(StrBuffer) > MaxLen then
StrBuffer[0] := Chr( MaxLen);
GetText := StrBuffer;
function IsSelected (Item: Integer): Boolean; virtual;
Use IsSelected to check if a specific item is also the focused item.
IsSelected returns True if the entry specified by Item is currently
selected, False otherwise.
procedure HandleEvent( var Event: TEvent ); virtual;
Override: As needed.
Performs event processing for the TListViewer, including mouse navigation
and clicking in the list box to select an item, the use of the space bar
to perform keyboard selection, and all keyboard navigation keys (up and
down arrow, PgUp, PgDn, Home, End, etc). Navigation events that move
through the list automatically cause the associated scroll bars to update
themselves.
See: See Chapter 11, "Turbo Vision Tutorial" in the Borland Pascal
Developer's Guide for an example.
constructor Load( var S : TStream );
Loads a TListViewer object from stream S, and also loads any associated
scrollbars.
procedure SelectItem( Item: Integer ); virtual;
This is intended to be used and overridden by descendants, to make the
Item'th entry in the list selected. This routine is essentially
equivalent to TListViewer.FocusItem.
procedure SetRange( ARange : Integer );
Sets the Range field to ARange or the number of items in the list and
automatically adjusts the scroll bars, as needed. If the new range would
put the current Focused item value out of range, then Focused is reset to
zero.
See: TListViewer.Range
procedure SetState( AState: Word; Enable: Boolean); virtual;
Basically, this calls TView.SetState to set or reset the sfOptions bits in
the TView.State variable.
See: sfOptions, TView.State
procedure Store( var S: TStream);
Stores this TListViewer object onto stream S, and stores any associated
scroll bars.
TMenuBar object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TMenuView
TMenuBar
TMenuBox
Discussion
The TMenuBar object manages the menu bar across the top of the application
screen. Most applications merely call the TMenuBar.Init method with a
series of nested NewMenu, NewSubMenu, NewLine and NewItem function calls
to create an entire list of pull down menu items. It's unlikely that you
will use any other TMenuBar methods.
Example
MenuBar := New(PMenuBar, Init(Bounds, NewMenu(
NewSubMenu('~R~un', hcNoContext, NewMenu(
NewItem('~R~un', '', 0, cmRunProgram, hcNoContext,
NewItem('~E~dit', 'Alt-E', kbAltE, cmEdit, hcNoContext,
NewItem('~V~iew', 'Alt-V', kbAltV, cmView, hcNoContext,
NewItem('~U~se DOS','Alt-D', kbAltS, cmUseDOS,
hcNoContext,
NewItem('E~x~it', 'Alt-X', kbAltX, cmQuit, hcNoContext,
nil)))))),
...
Fields
None
Methods
procedure Draw; virtual;
Draws the menu bar on the display and highlights the selected item.
procedure GetItemRect(Item: PMenuItem; var R: TRect); virtual;
This internal method is used to determine if a mouse click occurred on a
particular menu item.
constructor Init(var Bounds: TRect; AMenu: PMenu);
Creates an initializes the menu bar. See the example above, and also look
at NewMenu, NewSubMenu, NewItem, and NewLine functions.
TMenuBox object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TMenuView
TMenuBar
TMenuBox
Discussion
The TMenuBox object implements the menu box that drops down from the menu
bar. TMenuBox displays the contents of the pulldown menu and processes
the keyboard and mouse inputs to make a selection.
Commonly Used Features
Most applications will never reference the TMenuBox object directly.
Instead, pulldown menus are created with the NewSubMenu function nested
within the TMenuBar.Init constructor. However, it is possible to use the
TMenuBox as a standalone pulldown menu providing a group of items from
which to select. For instance, sometimes its not practical to display
every option on one of the standard pulldown menus. Instead, consider
adding a submenu that gets displayed only when one of the standard
pulldown options is selected or perhaps as the result of a button press in
a dialog box. The example code below shows how to create and execute a
standalone pulldown menu, here emulating the Watches submenu from the
Turbo Pascal IDE's Debug menu.
Example
AMenuBox is a PView-type variable. When passed to DeskTop^.ExecView(),
the standalone menu is displayed at the location specified by Bounds.
Oncea selection is made from the menu, Command is set to the cmXXXX
constant corresponding the selected item.
Begin
Bounds.Assign(10,5, 40,12 );
AMenuBox := New(PMenuBox, Init( Bounds, NewMenu(
NewItem('~A~dd Watch', 'Ctrl-F7', kbCtrlF7, cmAddWatch,
hcNoContext,
NewItem('~D~elete Watch', '', 0, cmDelWatch, hcNoContext,
NewItem('~E~dit Watch...', '', 0, cmEditWatch,
hcNoContext,
NewItem('~R~emove all Watches', '', 0, cmRemWatch,
hcNoContext,
nil))))),nil));
Command := DeskTop^.ExecView(AMenuBox);
End;
Fields
None
Methods
procedure Draw; virtual;
Displays the menu box and contents.
procedure GetItemRec(Item: PMenuItem, var R: TRect); virtual;
GetItemRec is used internally determine if the particular Item was
selected by a mouse click.
constructor Init(var Bounds: TRect; AMenu: PMenu; AParentMenu: PMenuView );
Use Init to create a new TMenuBox object, where Bounds describes both the
size and location of the menu box, and AMenu is normally constructed from
a series of nest calls to NewMenu, NewItem and so on. For standard
pulldown menus, AParentMenu points to the menu bar, but for standalone
menu boxes, this parameter can be set to nil.
TMenu type
------------------------------------------------------------
Declaration: TMenu = record
Items : PMenuItem;
Default : PMenuItem;
end;
Unit: Menus
Purpose:
TMenu is used for building up menu bar and pulldown menu records and is
created by the NewMenu function. TMenu records are unlikely to be used
except for creation and maintanance of the menu bar object.
TMenuItem type
------------------------------------------------------------
Declaration:
{ TMENUITM.PAS }
PMenuItem = ^TMenuItem;
TMenuItem = record
Next: PMenuItem;
Name: PString;
Command: Word;
Disabled: Boolean;
KeyCode: Word;
HelpCtx: Word;
case Integer of
0: (Param: PString);
1: (SubMenu: PMenu);
end;
Unit: Menus
Purpose:
TMenuItem records are created using the NewItem, NewLine and NewSubMenu
functions, and are used to store a list of TMenuItem records describing
each menu item on a pulldown menu. The various fields store the values
passed to the NewItem or NewSubMenu functions as follows:
Next points to the next item in the menu structure, or is nil if it is
the last item in the menu.
Name is a PString pointer to the item name, or nil in the case of a
NewLine.
Command contains the cmXXXX constant value used as an evCommand message
to your view's HandleEvent procedure when the item is selected from the
menu.
Disabled is False normally, but set to True if the item has been
disabled.
KeyCode contains the hot key's scan code, if any, or zero if there is
not hot key defined for this item.
HelpCtx contains the help constant identifier for use in an on-line help
system.
The last variant field contains either Param, a pointer to the text
displayed next to a menu item, normally the hot key prompt, such as
'Alt-A' (or nil if there is no parameter string), or SubMenu as a
pointer to the submenu structure.
See: Chapter 11, "Turbo Vision Tutorial", NewItem, NewLine, NewSubMenu,
TMenu.
TMenuStr type
------------------------------------------------------------
Declaration:
TMenuStr = String[31];
Unit: Menus
Purpose:
TMenuStr defines the string type used for storing menu item names, and
limits menu names and item names to a maximum of 31 characters in length.
See: NewItem, NewSubMenu
TMenuView object
------------------------------------------------------------
Turbo Vision Hierarchy
TMenuView
TView
TMenuView
TMenuBar
TMenuBox
Discussion
TMenuView implements much of the functionality for TMenuBar and TMenuBox
and is not used directly. Refer to TMenuBar and TMenuBox for examples of
the menu facilities. Most of the methods shown below are used internally
by the derived object types and rarely used in a typical application.
Fields
ParentMenu: PMenuView; { Read only }
Points to the TMenuView-type object that owns this menu object.
Menu: PMenu; { Read only }
Points to a TMenu-type record, which in turn points to a linked list of
TMenuItem records defining each of the menu items that appear on the menu.
See: TMenu type, TMenuItem type
Current: PMenuItem; { Read only }
Keeps track of which menu item is the currently selected one.
Methods
function Execute: Word; virtual;
Override: Never
ExecView calls Execute to process the modal nature of the pulldown menu.
Execute returns cmXXXX constant that was defined for the menu selection,
or 0 if the Esc key was pressed and nor selection was made.
function FindItem(Ch: Char); PMenuItem;
FindItem scans through the menu box structure looking for a menu item that
has Ch has its shortcut key, and returns a pointer to that menu item, or
nil if not matches were found.
procedure GetItemRect(Item: PMenuItem; var R: TRect); virtual;
This internal method helps the menu code determine which menu item on
which a mouse click occurred.
function GetHelpCtx: Word; virtual;
Returns the value of the help context constant for the current menu item.
If the menu item's help context is hcNoContext, then GetHelpCtx checks the
owner of the menu and return's its help context.
function GetPalette: PPalette; virtual;
Returns a pointer to CMenuView, the default color palette for menus.
See: CMenuView
procedure HandleEvent(var Event: TEvent); virtual;
Override: Never.
Process all events for the menu object.
function HotKey(KeyCode: Word): PMenuItem;
Scans through the menu structure looking for the menu item that has the
hot key specified by KeyCode defined, and if found, returns a pointer to
that menu item. Otherwise, if KeyCode is not found, then it returns nil.
constructor Init(var Bounds: TRect);
Creates a view having the indicated Bounds. TMenuView.Init should only be
called by TMenuBar and TMenuBox.
constructor Load(var S: TStream);
Creates and loads a TMenuView object from stream S.
procedure Store(var S: TStream);
Writes the TMenuView object to stream S.
TObject object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TCollection
TStream
TStringList
TStrListMaker
TResourceFile
Discussion
Nearly all objects used in Turbo Vision are defined from this root object
type, and all objects written to streams must be descended from TObject.
Fields
None
Methods
destructor Done;
Disposes a dynamically allocated object.
procedure Free;
Descendants of TObject actually call TObject.Free to dispose of the
dynamically allocated object.
constructor Init;
TObject.Init is called from all descended object's Init constructors.
Descendant's should always call their parent's Init method prior to
performing their own initialization since TObject carefully zeroes all
allocated fields as part of its initialization.
TPalette type
------------------------------------------------------------
Declaration:
TPalette = String;
Unit: Views
Purpose:
Defines the data type used for storing color palettes. Since all color
palettes are equivalent to strings, you can use, if you wish, all of the
various string manipulation functions, including indexing, Copy, Delete,
Insert and so on.
See: Chapter 13, "More Turbo Vision Features"
TParamText object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TStaticText
TLabel
TParamText
Discussion
TParamText is essentially equivalent to TStaticText, for displaying text
strings in dialog boxes except that TParamText provides enhanced
flexibility in the formatting of the text strings. The string parameter
passed to TParamText.Init may contain embedded formatting information and
is passed directly to the FormatStr procedure.
See: FormatStr, TStaticText, TLabel, TDialog
Commonly Used Features
If you use this object type, you will probably create the object with the
Init constructor and then insert it into a dialog and are unlikely to
directly access the other methods. You will need to directly assign a
value to the ParamList pointer as shown in the example.
Example
This example of TParamText shows how a variable FileName might be inserted
into a TParamText derived object, AParam. Each time that the dialog is
displayed, or particularly if the dialog is normally stored in a resource
file, the FileName parameter can be automatically inserted into the
TParamText message prompt by changing Parameters.AParamStr to a new value.
var
AParam : PParamText;
Parameters : record
AParamStr : PString;
end;
...
{ Set up the contents of the Delete dialog }
with Dialog^ do
begin
...
{ Add the Delete Okay? }
Bounds.Assign ( 8, 2, 45, 3 );
AParam := New (PParamText,
Init( Bounds, 'Okay to Delete %s', 1 ));
Parameters.AParamStr := NewStr(FileName);
AParam^.ParamList := @Parameters;
Insert( AParam );
end; { with }
Control := DeskTop^.ExecView (Dialog);
Fields
ParamCount: Integer;
Specifies the number of parameters in the ParamList^ parameter array or
record.
ParamList: Pointer;
Points to the parameter array or parameter record that specifies the data
values to be inserted into the Text string (which is inherited from
TStaticText). See FormatStr for a complete description of string
formatting.
Methods
function DataSize: Word; virtual;
Used in conjunction with GetData and SetData, DataSize returns the size in
bytes of the data storage used by a TParamCount object.
procedure GetText(var S: String); virtual;
Calls FormatStr( S, Text^, ParamList^ ) to format and merge the parameters
in TParamText.ParamList^ with the TParamText.Text^ string (Text is a field
inherited from TStaticText to hold the contents of this item's text) and
produces the resultant output string S.
See: FormatStr, TParamText.ParamList, TParamText.Text, TStaticText.Text
constructor Init(var Bounds: TRect; AText: String; AParamCount: Integer);
TParamText.Init calls TStaticText.Init to create the object, and then
stores AParamCount into TParamText.ParamCount. AText is the text to be
used for the message prompt. You must separately assign the parameter
array or record to ParamList.
constructor Load(var S: TStream);
Creates and reads a TParamText object from stream S.
procedure SetData(var Rec); virtual;
Copies the number of bytes specified by DataSize into Rec.
procedure Store(var S: TStream);
Writes the TParamText object to stream S.
TPoint object
------------------------------------------------------------
Turbo Vision Hierarchy
Fields
X: Integer;
Y: Integer;
Defines a point (X,Y) on the screen.
TProgram object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TGroup
TProgram
TApplication
Discussion
TProgram contains most of the functionality present in TApplication.
Usually you will derive your application directly from TApplication but it
is possible to derive it from TProgram instead. All Turbo Vision programs
must be derived from either TApplication (preferred) or TProgram.
Commonly Used Features
The following are the frequently used methods of TProgram: Init, Done,
HandleEvent, Idle, InitMenuBar, InitStatusLine, OutOfMemory, Run,
SetScreenMode
Example
See TVSHELL8 in the Borland Pascal Developer's Guide for a complete
example of a finished application using the frequently used methods of
TProgram (except Idle).
Fields
None
Methods
destructor Done;
TProgram.Done disposes of all the application related objects, including
StatusLine, MenuBar and DeskTop and essentially terminates the Turbo
Vision program.
procedure GetEvent(var Event: TEvent); virtual;
This is the application's event processing loop. GetEvent checks for
mouse and keyboard events and since TProgram owns all of the application's
views, GetEvent sends the event record to the appropriate view for
processing. If no events occurred, then GetEvent calls TProgram.Idle (see
TProgram.Idle).
function GetPalette: PPalette; virtual;
Returns a pointer to the default color palette for the application. Since
TProgram.GetPalette points to the application level palette, of which
there are 3, CColor, CBlackWhite and CMonochrome, GetPalette checks the
AppPalette variable to determine which application palette is the
currently active palette.
See: appPalette, apXXXX constants, CBlackWhite, CColor, CMonochrome
procedure HandleEvent(var Event: TEvent); virtual;
Override: Always, to implement an application's functions.
Every application will override HandleEvent (but don't forget to call
TProgram.HandleEvent first), to process the cmXXXX commands returned by
the various menu selections and short cut keys.
See: Chapter 11, "Turbo Vision Tutorial", and TVSHELL8 for examples.
procedure Idle; virtual;
You can have your Turbo Vision application perform background tasks during
idle periods in the program's execution. To make use of idle time,
override TProgram.Idle to perform your background tasks (always remember
to call TProgram.Idle as the first statement within your overwritten Idle
procedure). TProgram.Idle should only perform operations that can be done
quickly as Idle is called from within TProgram's GetEvent loop. This
means that if TProgram.Idle takes a lengthy time to complete operation,
your program's execution appear to be slow down to unacceptable levels.
constructor Init;
Initialize's Turbo Vision support for an application, including the video
screen modes, and calls InitDeskTop, InitStatusLine and InitMenuBar. You
must override the last three methods to provide your application's status
line and menu bar definitions.
procedure InitDeskTop; virtual;
Initializes an application's TDeskTop object and sets the global DeskTop
pointer to point to this object. See the listing given in TBackground for
an example of how this method can be overriden to create a TDeskTop object
other than the default desktop.
procedure InitMenuBar; virtual;
You should always override InitMenuBar so that it creates a new menu bar
and associated pulldown menus and setsMenuBar to point to the new menu
structure. See Chapter 11.
procedure InitScreen; virtual;
This internal routine is called by TProgram.SetScreenMode to initialize
all of the Turbo Vision screen mode dependant values: ShadowSize,
AppPalette and ShowMarker.
procedure InitStatusLine; virtual;
You should always override InitStatusLine so that it creates a new
statusline and set the global variable StatusLine to point to the new
status line structure. See Chapter 11.
procedure OutOfMemory; virtual;
Whenever TProgram.ValidView finds that LowMemory is True, meaning that the
low memory buffer area has been entered, TProgram.ValidView calls
OutOfMemory. You should override this procedure to display an error or
warning message to the user with information about the low memory problem.
See: LowMemory, TProgram.ValidView
procedure PutEvent(var Event: TEvent); virtual;
PutEvent inserts Event into the pending Event queue so that the next call
to GetEvent returns Event.
procedure Run; virtual;
Calls the inherited TGroup.Execute method, which is the main event loop of
the application.
procedure SetScreenMode( Mode: Word );
When you need to switch between the 3 application level color palettes,
CColor, CBlackWhite or CMonochrome, or switch between 25- and 43/50-line
screen modes, call TProgram.SetScreenMode, setting the Mode parameter with
the values smCO80, smBW80 or smMono, OR'd, as needed, with smFont8x8. See
the procedure SetVideoMode for complete details; normally you will call
TProgram.SetScreenMode rather than SetVideoMode.
function TProgram.ValidView(P: PView): PView;
ValidView is used to determine if a newly constructed view was created
appropriately. It does this by checking the LowMemory flag and if True,
automatically calls TProgram.OutOfMemory. ValidView also insures that P
is not nil, and if any errors are founds, ValidView returns a nil pointer.
You can use ValidView to check the instantiation of new views directly as
they are inserted into a group.
DeskTop^.Insert(ValidView( New( PStaticText, Init( ... ) ) ) );
This results in an automatic error handling sequence, calling OutOfMemory
or what not, as Insert will ignore a nil pointer and will not insert the
failed view.
See: TProgram.OutOfMemory, TView.Valid, TGroup.Valid, Chapter 13, "More
Turbo Vision Features".
TRadioButtons object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TView
TCluster
TRadioButtons
TCheckBoxes
Discussion
Use TRadioButtons to implement groups of radio buttons in dialog boxes.
Chapter 11 in the Borland Pascal Developer's Guide contains a tutorial on
the creation and use of TRadioButtons objects.
See TCheckBoxes, TDialogs
Commonly Used Features
Most applications will use the inherited TCluster.Init method to
initialize a radio button group, and then Insert the group into the
dialog. There is little need to use any of the other available methods
directly.
Example
This example shows creating and inserting a radio button into an owner,
which is normally a TDialog object, and linking it to a TLabel prompt
line:
Bounds.Assign(3, 2, 20, 4);
VideoOptions := New (PRadioButtons, Init (Bounds,
NewSItem('~2~5 lines',
NewSItem('~4~3/50 lines',
nil))
));
Insert(VideoOptions);
Bounds.Assign( 3, 1, 20, 2);
Insert( New( PLabel, Init( Bounds, 'Screen size', VideoOptions)));
Fields
None
Methods
procedure Draw; virtual;
Displays each radio button, including the "( )" selection fields.
function Mark(Item: Integer): Boolean; virtual;
Use Mark to determine if a specific radio button, specified by Item, is
currently pressed.
procedure MovedTo(Item: Integer); virtual;
MovedTo is identical to Press and sets the Item'th radio button to
"pressed".
procedure Press(Item: Integer); virtual;
Makes the Item'th radio button the currently pressed radio button.
procedure SetData(var Rec); virtual;
Copies the Value and Sel fields from Rec, and then sets the selected item
indicated by Sel to the "pressed" state.
TRect object
------------------------------------------------------------
Turbo Vision Hierarchy
TRect is a standalone object.
Discussion
TRect primarly defines two coordinates, A and B, which are the upper left
and the lower right corners of a rectangle. TRect parameters are used
throughout Turbo Vision to specify the screen location and size of
windows, dialog boxes and entry fields.
Commonly Used Features
The mostly commonly used method is Assign, used to initialize the
coordinate values, but several utility methods also enable quick changes
in the values of the coordinate fields and making copies of the TRect
object.
Example
var
Bounds: TRect;
ARectangle : TRect;
...
{ Initialize to the coordinates (0,0) and (80,2) }
Bounds.Assign(0, 0, 80, 2);
...
{ Copy the contents of Bounds to ARectangle }
ARectangle.Copy( Bounds );
Fields
A: TPoint;
A TPoint defining the upper left corner of a rectangle.
B: TPoint;
A TPoint defining the lower right corner of a rectangle.
Methods
procedure Assign( XA, YA, XB, YB: Integer);
Sets A.X := XA, A.Y := YA, B.X := XB and B.Y := YB.
procedure Copy(R: TRect);
Sets the A and B fields to the values in R.
procedure Move(ADX, ADY: Integer);
Adds ADX to the X values and ADY to the Y values of A and B.
Sets A.X := A.X + ADX, B.X := B.X + ADX and sets A.Y := A.Y + ADY, B.Y :=
B.Y + ADY.
procedure Grow(ADX, ADY: Integer);
Adjusts A and B as follows:
A.X := A.X - ADX; B.X := B.X + ADX;
A.Y := A.Y- ADY; B.Y := B.Y + ADY;
procedure Intersect(R: TRect);
Determines the area that this rectangle overlaps with the rectangle
specified by R, and sets A and B to the intersection of the two
rectangles.
procedure Union(R: TRect);
Creates a new rectangle that encompasses A and B and the rectangle R.
function Contains(P: TPoint): Boolean;
Returns True if P lies within the rectangle specified by A and B.
function Equals(R: TRect): Boolean;
Compares A and B to R, and returns True if they are equal, and False if
they are not.
function Empty: Boolean;
If A and B are equal, then A and B describe a rectangle containing no
spaces. Empty returns True if A = B.
TResourceFile object
------------------------------------------------------------
Turbo Vision Hierarchy
TObject
TResourceFile
Discussion
TResourceFile is a special purpose random access TStream that let's you
find records by a key string instead of a record number. Using
TResourceFile, you can implement simple data base retrievals, as well as
store Turbo Vision components.
See Chapter 16, "Resources" in the Borland Pascal Developer's Guide for a
complete discussion and tutorial on the use of TResourceFile objects.
Commonly Used Features
In addition to Init, Put, Get and Done are the most frequently used
methods of the TResourceFile object.
Fields
Stream: PStream;
Points to the stream used by this TResourceFile object.
Modified: Boolean;
If the file has been modified, then this flag is set to True. The
TResourceFile.Flush procedure checks this flag to determine if it should
update the resourc file.
Methods
function Count: Integer;
Computes and returns the number of items or resources stored in the file.
procedure Delete(Key: String);
Removes the key from the index and marks the space it previously occuppied
as being deleted.
See TResourceFile.SwitchTo for a method to reclaim the now unused space.
destructor Done; virtual;
Calls TResourceFile.Flush and disposes of the index collection and
resource stream file.
procedure Flush;
Checks the Modified flag, and if True, updates the resource stream file,
and then resets Modified to False.
function Get(Key: String); PObject;
Uses Key as an index into the resource and returns a pointer to the object
that it references, or nil if the Key is not in the file.
See TResourceFile.Put
constructor Init( AStream: PStream );
TResourceFile.Init is called after opening a stream. The opened stream is
passed as a parameter to Init and becomes the stream that holds the
resource file. See Chapter 16, "Resources".
function KeyAt(I: Integer): String;
Use KeyAt to scan through the entire resource file. I is an index to each
resource in the file, numbered 0 to TResourceFile.Count minus 1. KeyAt
returns the string corresponding to the key value at the I'th index
position.
procedure Put(Item: PObject; Key: String);
Stores the object pointed to by Item into the resource file, using the
specified Key.
See TResourceFile.Get
function SwitchTo(AStream: PStream; Pack: Boolean): PStream;
Use SwitchTo to copy the current resource file to another stream specified
by AStream. If Pack is True, SwitchTo will not copy objects marked as
deleted, thereby compressing the resulting resource file.
See: TResourceFile.Delete